<html xmlns="http://www.w3.org/1999/xhtml" id="debugging"
      xmlns:d="docbook">
<head>
  <title>Debugging</title>
</head>

<body>


<h1>Debugging</h1>

<h2>Using the Debugger</h2>

<p>When you run an application with debugging enabled, the application
is compiled with instrumentation to detect runtime errors, and the
debugger window appears within the application canvas.  The debugger
provides these features:</p>
<ul>
  <li>The top portion of the debug window displays a scrolling list of
  debug messages.  These include warning messages that the OpenLaszlo Runtime Library displays, as well as the arguments to calls to
  <method>Debug.write</method>.</li>
  
  <li>The command-line portion of the debug window can be used to
  evaluate JavaScript statements and expressions within the context of
  the running application.  Use this to inspect the program state, to
  test the behavior of functions and methods on various arguments, and
  to explore the LZX API.</li>
  
  <li>Warnings for runtime errors such as undefined variables and
  functions are detected, and printed to the debug console.</li>
</ul>

<img class="screenshot" src="images/debugger.png"/>

<example title="The Debugger window">
&lt;canvas height="150" debug="true"/&gt;
</example>

<note>Debugging may cause the application to run more slowly, even if
the debugger window is not visible.</note>

<p>See <xref linkend="program-development.debugging"/> for a quick
overview of the debugger.</p>

<h3><a name="enabling-the-debugger"/>Enabling the Debugger</h3>

<p>There are three ways to turn on the debugger in your application:</p>

<dl>
<dt>The <attribute>debug</attribute> attribute</dt>
<dd><p>The debugger is enabled on if the canvas <attribute>debug</attribute> attribute is set to true:</p>
<example title="The &lt;canvas&gt; debug attribute">
&lt;canvas height="150" debug="true"/&gt;
</example></dd>

<dt><span>The "Debug" button</span></dt>
<dd><p>Press the "Debug" button on the <glossterm>developer console</glossterm> to request a copy of the application with debugging enabled.  This is equivalent to recompiling the application with the <code>debug="true"</code>.</p>

<img class="screenshot" src="images/debug-button.png"/></dd>

<dt><d:para>The <code>debug</code> query parameter</d:para></dt>
<dd><p>Edit the URL that is used to request the application to include
the <code>debug=true</code> <glossterm>query parameter</glossterm>.
This is equivalent to pressing the "Debug" button in the developer
console.</p>

<img class="screenshot" src="images/debug-query-parameter.png"/>

<p>See the<a href="${deploy}/request-types.html">System Administrator's Guide</a> for more information
about request types.</p></dd>

<?ignore
<dt><code>&lt;include href="debugger"/&gt;</code> 
<dd><p>Add the line <code>&lt;include href="debugger"/&gt;</code> to your source file to include the debugger <em>component</em>.</p>

<example title="Using &lt;include&gt; to include the debugger">
&lt;canvas height="150"&gt;
  &lt;include href="debugger"/&gt;
&lt;/canvas&gt;
</example>

<note>Unlike the other methods for turning on the debugger, this method does not turn on runtime error checking (<xref linkend="debugging.runtime-error-checking"/>).  It only includes the debugger component.</note></dd>
?>

</dl>

<h3><a name="runtime-error-checking"/>Runtime Error Checking</h3>

<p>Enabling the debugger <?ignore Using any of the first three methods in <xref linkend="debugging.enabling-the-debugger"/>?> has two effects:</p>
<ul>
  <li>It includes the debugger visual component.  This displays debug messages, and has a command line interface for evaluating JavaScript statements.</li>
  <li>It compiles the application with additional instrumentation to perform <dfn>runtime error checking</dfn>.  Certain classes of erroneous code (below) result in warnings that are logged to the debug window.</li>
</ul>

<p>A program that is compiled with runtime error checking will contain code that checks for the following conditions:</p>

<table summary="Runtime error checks">
<tr>
  <th>Condition</th>
  <th>Example</th>
  <th>Notes</th>
</tr>
<tr>
  <td>Reference to undefined variable</td>
  <td><code>var w = canvs.width</code></td>
  <td><varname>canvs</varname> is not defined.  (There is a global
  variable named <code>canvas</code>, instead.)</td>
</tr>
<tr>
  <td>Reference to undefined property</td>
  <td><code>var w = canvas.widt</code><d:footnote id="footnote.no-check-for-brackets"><p>The debugger does not warn about undefined references if the subscript notation is used: <code>canvas['widt']</code>, which is otherwise equivalent to <code>canvas.widt</code>, does not generate a warning.  This can be used as a workaround for the lack of the ECMASCript <code>in</code> relational operator in OpenLaszlo ECMASCript, to test whether an attribute exists.</p></d:footnote></td>
  <td><varname>canvas</varname> does not have a <code>widt</code> property.  (The name of the property is <code>canvas.width</code>.)</td>
</tr>
<tr>
  <td>Call to undefined method</td>
  <td><code>LzBrowser.getVerson()</code></td>
  <td><code>LzBrowser.getVerson</code> (with no "i") is not defined.</td>
</tr>
<tr>
  <td>Call to undefined function</td>
  <td><code>var n = parseInteger("123")</code></td>
  <td><code>parseInteger</code> is not defined.  (There is a JavaScript function <code>parseInt</code>.)</td>
</tr>
<tr>
  <td>Call to non-function</td>
  <td><code>var w = canvas.width()</code></td>
  <td><code>canvas.width</code> is a <classname>Number</classname>,
  not a <classname>Function</classname>.</td>
</tr>
</table>

<p>Each runtime exception warning is printed once per line per program run, not once each time the exception is encountered.  The following program will print one warning, not ten.</p>

<example>
&lt;canvas debug="true" height="150"&gt;
  &lt;method event="oninit"&gt;&lt;![CDATA[
    for (var i = 0; i &gt; 10; i ++) {
      canvas.width();
    }
  ]]&gt;&lt;/method&gt;
&lt;/canvas&gt;
</example>

<note>Turning on runtime error checking makes an application bigger,
and slower.  You should only perform size and speed optimization on
the non-debug version of a program.  Nonetheless, you will frequently
want to run the debug warning to see whether you have introduced any
runtime errors.</note>

<h3>Logging to the Debugger</h3>

<p>The top portion of the debugger window is the <dfn>debugger
log</dfn>.  Use <method>Debug.write</method> to print to the debugger
log.  This method is <dfn>variadic</dfn>: it takes any number of
arguments.  The text representations of the arguments are printed
to the debugger log, separated by spaces.</p>

<example title="Logging to the debugger">
&lt;canvas debug="true" height="150"&gt;
  &lt;script&gt;
    Debug.write('user code');
  &lt;/script&gt;
  &lt;button onclick="Debug.write('click', getMouse('x'))"/&gt;
&lt;/canvas&gt;
</example>

<p>Some object are <glossterm
baseform="inspect">inspectable</glossterm>.  See <xref
linkend="debugging.inspecting"/> for more about the inspect feature of
the debugger.  See <xref linkend="debugging.debug-tostring"/> to see
how to customize the display of objects within the debugger.</p>

<h3>Using the Evaluator</h3>

<p>The bottom portion of the debugger window is the
<dfn>evaluator</dfn>.  This is a command-line interface for evaluating
JavaScript expressions and statements within the application.  Enter a
JavaScript statement into this area and press the Enter key (in
single-line mode) or the Evaluate button (in multi-line mode) to
evaluate the statement within the application.  If the statement is an
expression, its result (if the result is not <code>undefined</code>)
is printed to the debugger log.  If it is a statement but not an
expression, it is executed for effect.</p>

<p>Examples of expressions are <code>canvas.x</code>,
<code>1+2</code>, and
<code>LzBrowser.LoadURL('http://www.laszlosystems.com/',
'_blank')</code>.  (The last expression returns the value
<code>undefined</code>, so the debugger does not print the expression
value in the debugger log.)  An example of a non-expression statements
is <code>for (int i = 0; i &lt; 10; i++) Debug.write(i)</code>.  This
is evaluated for effect, and the statement itself does not result in a
value, although each execution of the loop prints the value of
<varname>i</varname> to the debugger log.</p>

<p>The debugger can be used to define global variables.  Use the
<code>var</code> keyword to define a new global variable.  For
example, after evaluating <code>var n=100</code>, evaluating
<code>n+1</code> will print the value <code>101</code>.</p>

<note>The <code>var</code> keyword is only necessary to define
<em>new</em> global variables.  You do not need it to change the value
of existing variables.  For example, after evaluating <code>var
n=100</code>, you can evaluate <code>n=200</code> to change the value
of <varname>n</varname>.  You do not need to evaluate
<code>var n=200</code> (although the extra <code>var</code>
is harmless.)</note>

<p>You can also use <code>var</code> to create new global functions.
<code>var f = function (x) {return x+1}</code> creates a new function
named <varname>f</varname>, which can be used in subsequent
expressions such as <code>f(1)</code>.</p>

<h4>Functions and Expressions</h4>
<p>
Consider the following debugger evaluations. Notice that the second case is terminated with a semicolon; otherwise the expressions are identical:</p>
<pre>
lzx> function foo () { return 'Fu'; }
Function#0| foo
lzx> foo
WARNING: interactive-eval-2:-1: reference to undefined variable 'foo'
lzx> function foo () { return 'Fu'; }<span color="red">;</span>
lzx> foo
Function#2| foo
</pre>
<p>
In the first case, a function named 'foo' is created, but it is not the value of the global `foo`.  Instead the Debug evaluator returns a value which is that function object.  In the second case, the evaluator does not return a value, and the global `foo` <i>is</i> defined to be the function.  Why is that?</p>
<p>
The answer is that the debugger evaluator will first try to evaluate what you type as an expression, and if that fails, it will try to evaluate it as a statement.  The second form is clearly not an expression (think of what you type as having parentheses around it&#8212;the semi-colon forces the second form to be a statement list, with an empty second statement).  This distinction, although subtle, is correct ECMAscript semantics.  It is not whether you name a function or not that determines when a global definition will be made; rather, two things must be true: </p>
the function must be named, and 
the function declaration must occur in a statement context.
<p>
If the function declaration occurs in an expression context, all you have done is to create a named function object as the value of that expression, you have not defined that name as the function.
</p>

<p>Therefore, if you ever wonder why when you define a function in the debugger it does not behave as you expect, take a clue from what the evaluator prints out:  if it prints out a function object, all you did was create a function, not define a function.  Add the semi-colon after your definition and you will define the function (and not see a value printed).
</p>

<todo>Explain the single-line and multi-line mode of the evaluator</todo>

<todo>Screenshot</todo>

<h4>Debugger Variables</h4>

<p>Within a debugger expression, <code>_</code> refers to the value of
the previous expression.  For example, after evaluating
<code>canvas.width</code> to display the width of the canvas, you can
evaluate the expression <code>_/2</code> to display half this
width.</p>

<p>The debugger defines the following variables:</p>
<dl>
  <dt><code>_</code></dt>
  <dd>The result of the previous expression with a non-undefined value.</dd>
  <dt><code>__</code> [two underscore characters])</dt>
  <dd>The result of the expression prior to the previous expression.</dd>
  <dt><code>___</code> [three underscore characters]</dt>
  <dd>The result of the expression prior to the <code>__</code> expression.</dd>
</dl>

<h3><a name="inspecting"/>Inspecting Objects</h3>

<p>Evaluating <code>Debug.write(<var>object</var>)</code>, where
<code><var>object</var></code> is an expression that evaluates to a
JavaScript object, displays an <dfn>inspectable representation</dfn>
of the object in the debugger.  <!--An inspectable representation is displayed
with both its class and its <glossterm>printable representation</glossterm>.-->  Clicking on an
inspectable object displays its non-private properties and their
values.  Those values which are objects are also displayed as
inspectable objects, so that they can be clicked on as well.</p>

<p>An object's <dfn>private properties</dfn> are those whose names begin with <code>$</code> or <code>___</code> (three underscore characters). These names are used by the compiler and by the OpenLaszlo Runtime Library implementation, respectively, and are not part of the documented API for the object.</p> 

<p>An <dfn>inspectable object</dfn> can be an OpenLaszlo Runtime Library object such as a
window or <classname>LzDataset</classname>, or a built-in JavaScript
object: for example, an array such as <code>[1, 2, 3]</code>, or a
<classname>Object</classname> such as <code>{a: 1, b: 2}</code>.</p>

<p>The <method>Debug.inspect</method> function also displays the object and
its properties.  Evaluating <code>Debug.inspect(<var>object</var>)</code> is
equivalent to evaluating <code>Debug.write(<var>object</var>)</code> and
then clicking on the object's representation.</p>

<note><method>Debug.write</method> behaves differently depending on whether its argument is a string or a non-string object.  Note the difference between the two calls to <method>Debug.write</method> in the example below.</note>

<example title="Two ways of calling Debug.write">
&lt;canvas debug="true" height="150"&gt;
  &lt;method event="oninit"&gt;
    Debug.write('subviews: ' + canvas.subviews); <co><p>The (only) argument to <method>Debug.write</method> is a string, so the value of <code>canvas.subviews</code> is not inspectable.</p></co>
    Debug.write('subviews:',   canvas.subviews); <co><p>The second argument to <method>Debug.write</method> is an non-string Object, so it is inspectable.</p></co> 
  &lt;/method&gt;
&lt;/canvas&gt;
</example>

<h2>Configuring the Debugger</h2>
<h3>Debugger Window Position</h3>

<p>By default, the debugger comes up over the top left corner of your
application. You can change the basic properties of the debugger by
including the <tagname>debug</tagname> tag in your app, like this:
<code>&lt;debug x="100" y="100" height="500"/&gt;</code>.</p>

<p>Note that this does not <em>enable</em> the debugger; it merely
configures its appearance when the debugger is enabled.  You still
have use one of the methods in <xref
linkend="debugging.enabling-the-debugger"/> to enable debugging.  The
effect of this is that you can leave the <tagname>debug</tagname> in
your program at all times (including in production code), and it will
only have an effect when debugging is enabled.</p>

<h3><a name="debug-tostring"/>Customizing <method>Debug.write</method></h3>

<p><method>Debug.write</method> displays the <dfn>printable representation</dfn> of an object.  Where possible, the representation of an object is what you would type to represent that object in a program.  This is the case for instances of <dfn>Singleton</dfn> types (types with only a single instance, e.g., <classname>Undefined</classname> and <classname>Null</classname>) and for instances of <dfn>Atomic</dfn> types (types whose members have only a single value, no properties; e.g., <classname>Boolean</classname> or <classname>Number</classname>).  Instances of <classname>String</classname>s are normally not presented in this fashion (i.e., they are not quoted), as usually they are either a message or formatting.  Instances of <dfn>compound types</dfn> (types with properties, e.g., <classname>Array</classname> and <classname>Object</classname>) and Strings that are longer than <code>Debug.printLength</code> are printed in <dfn>inspectable</dfn> format:
</p>
<blockquote>
<code>&#xAB;<var>type</var>(<var>length</var>)#<var>id</var>|<var>name</var>&#xBB;</code>
 </blockquote>
<p>
where:
</p>
<dl>
<dt>type</dt>
<dd>is the type of the object, as computed by <method link="false">Debug.__typeof</method>.  You can customize this field by defining a <code>String</code>-valued property <code>_dbg_typename</code> or a method yielding a <code>String</code> of the same name on your class</dd>
<dt>length</dt>
<dd>is the length of the object, if it is of a type that has a length, such as <classname>Array</classname> or <classname>String</classname></dd>
<dt>id</dt>
<dd>is a unique identifier that can be used to visually distinguish objects whose printed representation may be the same but which are not in fact the same object</dd>
<dt>name</dt>
<dd>is a descriptive name of the object, as computed by <method link="false">Debug.__String</method>.  You can customize this field by defining a <code>String</code>-valued property <code>_dbg_name</code> or a method yielding a <code>String</code> of the same name on your class</dd>
</dl>
<p>
By default an object is described by
its properties, a function by its name (if available).</p>

<p>Descriptions and Strings are abbreviated to the first
<code>Debug.printLength</code> characters.  This property defaults to
<code>1024</code>.  You can see all the properties of an abbreviated
object, or all of a string by inspecting it (but take care to check
the length of the object &#x2014; it may take a very long time to
print if it is large).</p>
<p>
When the debugger prints an object, if the type part of the description is enclosed in ?'s, it means that the object is potentially corrupted. (Technically it means that <tt>object instanceof object.[[prototype]].constructor</tt> is not true.)</p>
<h2 id="logging-to-the-server">Logging to the Server</h2>

<p>Messages can be written from an LZX application to the
<glossterm>server log</glossterm> through the use of the
<code>debuglog=true</code> query parameter and the <method>Debug.log</method>
method.</p>

<todo>Examples</todo>

<p>See the <a href="${deploy}/logging.html">System Administrator's Guide to Delpoying OpenLaszlo Applications</a>  for information about configuration
and reading the server log.</p>
<h2>Formatting Output</h2>
<p>
The debugger has capabilities for formatting output according to control strings.
</p>

<h3>Using 'printf' conversions</h3>
<p>
<tt>Debug.formatToString</tt> produces formatted output to a string, formatting its arguments according to the control string:</p>

<ul>
	<li>The standard <tt>printf</tt> conversions are accepted, with the exception of <tt>a</tt>, <tt>n</tt>, and <tt>p</tt>. </li>
	<li><tt>e</tt>, <tt>f</tt>, and <tt>g</tt> conversions are accepted but equivalent to <tt>f</tt>.  </li>
	<li>The <tt>h</tt> and <tt>l</tt> length modifiers are accepted but ignored.  No errors are signalled for invalid format controls or insufficient arguments.</li>
</ul>


<p>There is an additional format specifier <tt>w</tt> that formats the argument as if by <tt>Debug.__String</tt> with the 'pretty' option and creates a 'hotlink' so the object can be inspected.  If alternate format is requested (#), <tt>w</tt> uses the full <tt>Debug.__String</tt> format used by <tt>Debug.write</tt>.  <tt>w</tt> format obeys <tt>Debug.printLength</tt>, binding it to the maximum width, if specified in the control string.</p>
<h3>Printing 'single-escape' characters</h3>
<p>
When the debugger prints a string and <tt>Debug.printPretty</tt> is false, it will escape all the <tt>SingleEscapeCharacter</tt>'s in the string (i.e., <tt>' " \ b \f \n \r \t \v</tt>).  For example:</p>

	<pre><tt>Debug.format('%#w', 'This is a "test"\nS\bring')  ->&#xAB;string#6| "This is a \"test\"\nS\bring"&#xBB;</tt></pre> 

<h3>Inspecting Warnings and Errors</h3>
<p>Warnings and Errors are 'inspectable'.  If you click on them, you will inspect the warning or error object.  If backtracing is enabled, a backtrace will be one of the properties of the object that you can inspect.  Inspecting the backtrace will reveal the recorded stack frames which record:  the function called, <tt>this</tt> and the arguments to the function.</p>

<h2>Monitoring object properties</h2>
<p><tt>Debug.monitor(who, what)</tt>: Takes an object and property name
and will emit a 'monitor message' each time that property is
changed.
</p>
<p>
<tt>Debug.unmonitor(who, what)</tt>: Turns that off.
</p>
<p>
A monitor message consists of a timestamp, the function that caused the change, the object and property, and the old and new
values.  E.g.:</p>
<pre><tt>
    MONITOR: [69227.23] LzLoader.initializeRequestObj: &#xAB;LoadMovie#0| __debugger.lzx (loaded)&#xBB;.valid: true -> true
    MONITOR: [69265.36] LzLoader.initializeRequestObj: &#xAB;LoadMovie#0| __debugger.lzx (loaded)&#xBB;.loaded: true -> false
    MONITOR: [69317.96] LzLoader.initializeRequestObj: &#xAB;LoadMovie#0| __debugger.lzx (loading)&#xBB;.loading: true -> false
    MONITOR: [69378.19] LzLoader.initializeRequestObj: &#xAB;LoadMovie#0| __debugger.lzx (initialized)&#xBB;.timedout: false -> false
    MONITOR: [69436.51] LzLoadQueue.makeRequest: &#xAB;LoadMovie#0| __debugger.lzx (initialized)&#xBB;.loading: false -> true
    MONITOR: [69702.58] LzLoader.returnData: &#xAB;LoadMovie#0| __debugger.lzx (loading)&#xBB;.loaded: false -> true
</tt>
</pre>
<h2>Tracing and Backtracing</h2>
<p>The debugger provides methods that allow you to see interactions between parts of your application.</p>
<h3>Tracing</h3>
<p>
When you invoke the <method>debug.trace()</method>, the debugger traces the named method of the object and prints a message to the Debug console each time it is called or returned from. When called, the message includes a timestamp, the name of the function and the arguments it was called with. When returned from, the message gives the name of the function and the value it returned (if any).  If backtraces are enabled, inspecting the message will reveal the call chain that caused the modification.
</p>
<h3>Backtracing</h3>
<p>
The configuration parameter <tt>compiler.debug.backtrace</tt>, when true, causes the compiler to instrument functions to maintain a call stack. You must recompile both the OpenLaszlo Runtime Library and your program if you change the setting of this parameter. It defaults to false because there is significant overhead introduced in enabling backtracing; in general it is only useful on small test cases.
</p>
<p>
The configuration parameter is set in the configuration file<tt> lps.config </tt>, as explained in the <a href="${deploy}/deployers-guide.html#deployers-guide.lps.properties">System Administrator's Guide</a>.</p>

<p>
To create your own backtrace at any time:
</p>
<pre><tt>
Debug.backtrace()</tt>
</pre>
<p>
There is an optional argument that is the number of frames to skip in creating the backtrace.
</p><p>
If you print a backtrace using <tt>Debug.write</tt>, it may be abbreviated, but clicking on it will reveal the full backtrace.
</p>
<p>
Debugger warnings will automatically include a backtrace. A backtrace snapshot can created by Debug.backtrace(). A backtrace is a subclass of array, converting it to a string will create a trace from innermost to outermost call, inspecting it will reveal the actual function objects that make up the array.
</p>
<p>
To get the full backtrace out of a debugger warning, you need to use:
</p><pre><tt>
__LzDebug.ObjectForID(NN)
</tt></pre>
<p>
Where NN is the object ID of the backtrace object, and then click on the resulting object to see the full trace.
</p>
<h2>Finding "memory leaks"</h2>
<p>
A running OpenLaszlo application allocates parts of available virtual memory to store objects.  When these objects are no longer needed the memory should be released by the application in order to become once again available for other use.  Sometimes unneeded memory is not properly released, in which case the application tends to slow down over time as less and less memory becomes available.  This is "leaking memory."  The OpenLaszlo debugger can help you find memory leaks.
</p><p>
Three methods on <tt>__LzDebug</tt> are used to find leaks:</p>

<ol>
	<li><method>markObjects()</method></li>
	<li><method>findNewObjects()</method></li>
	<li><method>whyAlive()</method></li>
</ol>

<p>
You use them in that order.  Typically, you will start up your program, run it for a bit until you think it has reached a steady state.  Then invoke <tt>__LzDebug.markObjects()</tt>.  This runs in the background and will mark all the objects that are currently in use.  When you see the output '''Trace Done''' you can move on to the next step.
</p>
<p>
You exercise your application in a way that you expect not to result in any retained storage (or some small amount of retained storage).  Run <tt>__LzDebug.findNewObjects()</tt>.  This also runs in the background and will find any new objects that have been allocated since the <tt>markObjects</tt> call that have not yet been garbage-collected.  When you see the output '''Trace Done''' you can move on to the next step.
</p>
<p>
Call <tt>__LzDebug.whyAlive()</tt>. This returns a ''leak list'', which you can call <tt>.toString()</tt> on to see ''&lt;why&gt; (&lt;size&gt;): &lt;what&gt;'' pairs.  ''&lt;why&gt;'' is the shortest path from <tt>_root</tt> that is keeping the object from being collected; ''&lt;size&gt;'' is a count of the slots in that object and all its descendants, which is a rough indication of the cost of the object; ''&lt;what&gt;'' is the debugger representation of the object.  You may want to set <tt>Debug.printLength</tt> to a larger value before converting to a string.  You can also inspect the ''leak list'' to see the objects that have been retained.
</p>
</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
